/**
 * Software License, Version 1.0
 * 
 * Copyright 2003 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgement:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgement may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or NaradaBrokering, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called NaradaBrokering, 
 * nor may Indiana University or Community Grids Lab or NaradaBrokering appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 *LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 *WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 *NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 *INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 *INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 *"VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 *LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 *ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 *GENERATED USING SOFTWARE.
 */
package cgl.narada.transport;

import java.util.Hashtable;
import java.util.Properties;

import cgl.narada.performance.PerformanceMeasurement;

/** The transport handler interface provides an intermediary between the
    protocol layers and the underlying transport implementations. Among the
    operations supported by the transport handler interface are the ability to
    <ul>
    <li>Load transport protocols for a certain type. 
    <li>Return information pertaining to the communication protocols that are 
    supported. 
    <li>Set up a communication <i>link</i> with the specified underlying 
    transport protocol, hostname, port num and other transport related factors.
    <li>Setting up alternate links to a given node.
    <li>Send data over a given link.
    <li>Send data of a certain <i>type</i> and deploying the appropriate link
    to facilitate data interchange.
    <li>Set the link performance monitoring intervals.
    <li>Shutdown communication services over a certain link.
    <li>Shutdown communication services over all links to a giev node.
    <li>Shutting down communication services over all links hosted by a given
    node and releasing communication resources associated with the hosting node
    </ul>

    @author Shrideep Pallickara
    $Date$
    $Revision$
*/

public interface TransportHandler {

  /** This is used to set the interval size at which tests on connection 
      status need to be performed. */ 
  public void setLinkStatusIntervals(long pingIntervals);
  
  /** Sets the interval size for a connection status checks for links
      managed by a specific link factory. */
  public void setLinkStatusIntervals(LinkFactory connectionHandler,
					long pingIntervals);
  
  /** Provides a list of transport services that are supported by the node*/
  public String[] getListOfCommunicationProtocolsSupported();
  
  /** Used to load a specific communications handler */
  public void loadCommunicationsOfType(Properties properties,
				       String communicationsType) 
    throws TransportException;
    
  /** This method is invoked by a link factory when it has 
      successfully set up a connection based on the specific transport
      protocol. */  
  public void registerLink(LinkFactory linkFactory, 
			      Link link);
  
  /** This method is to be invoked by link factories to report communication
      failure in one of the links (reported in argument) that it manages */
  public void manageLinkLoss(Link link);
  
  /** This method is to be invoked by link to request migration of
      transport protocols for one of its managed links */
  public boolean manageLinkMigrationRequest(Link link, 
					       String migrateTo);
  
  /** byte[] signifies the data received over a communication link. When
      this particular method is invoked it signifies a handshake. When a 
      link has been assigned a NaradaBrokering identifier this method will
      not be invoked by the link. 
      
      Certain data pertaining to the initialization of the link, checking
      for the status of the link etc. are not routed up to the transport
      handler.
  */
  public void dataReceived(byte[] data, String linkIdentifier);
  
  
  /** Upon receipt of data at a link that has an assigned NaradaBrokering
      identifier, this is the method that is used. */
  public void dataReceived(byte[] data, Object linkIdentifier);
  
  /** This is used to setup a communication link between 2 NaradaBrokering
      end points. The communication link type is specified in the arguments
  */
  public String setupLink(Properties linkProperties, String linkType) 
    throws TransportException;
  

  /** Used by the protocol layers to setup alternate links for communication
      based on the type of data that is being routed. Such alternate links
      also have a keepAlive timer associated with them, which ensure the
      garbage collection of the link after the time has expired */
  public void setupAlternateLink(Properties linkProperties, 
				    Object naradaBrokeringId,
				    String linkType, long keepAliveTime) 
    throws TransportException;
  
  /** Send data to an unitialized node (or a node to which connection is
      initiated for the first time). */
  public void sendData(byte[] data, String unitializedNode) 
    throws TransportException;
  
  /** Used to send a stream of bytes to a NaradaBrokering node */
  public void sendData(byte[] data, Object naradaBrokeringId) 
    throws TransportException;
  
  /** Send data to an unitialized node (or a node to which connection is
      initiated for the first time). This method also includes information
      regarding the type (audio/video/xml-attachments etc.) of the data
      encapsulated within the data stream.
  */
  public void sendData(byte[] data, String unitializedNode, String dataType) 
    throws TransportException;
  
  /** Used to send a stream of bytes to a NaradaBrokering node. This method 
      also includes information regarding the type (audio/video/xml-attachments
      etc.) of the data encapsulated within the data stream. */
  public void sendData(byte[] data, Object naradaBrokeringId, String dataType) 
    throws TransportException;
  
  /** Used to send a stream of bytes to a NaradaBrokering node, using a 
      specified communication type. The alternate link should have already
      been set up prior to the invocation of this method. This method also 
      includes information regarding the type (audio/video/xml-attachments
      etc.) of the data encapsulated within the data stream. */ 
  public void sendData(byte[] data, Object naradaBrokeringId, 
		       String linkType, String dataType) 
    throws TransportException;

  
  /** Enumerate the list of links available. What is returned is the linkID
      of all the links originating from this node. Returns NULL if no links
      are available. */
  public String[] enumerateLinks();

  /** Eliminate all links associated with communicating with the specified
      naradaBrokering id */
  public void closeLinks(Object naradaBrokeringId);
  
  
  /** Close all links associated with the specified Id. */
  public void closeLinks(String linkId);
  
  /** Close all links that have been initiated by the hosting node */
  public void closeAllLinks();

  public void disposeAllCommunicationResources();

  /** This method is invoked from the protocol layers, after assigning
      a NaradaBrokering id */
  public void mapLinkToClientNode(String linkId, 
				  Object naradaBrokeringId,
				  Object clientIdentifier);

   /** This method is invoked from the protocol layers, after assigning
      a NaradaBrokering id */
  public void mapLinkToBrokerNode(String linkId, 
				  Object naradaBrokeringId,
				  Object brokerConnectionIdentifier);
  
  /** Retrieves the management service */
  public PerformanceMeasurement getMeasurementService();

  public Hashtable getRegisteredLinks();
  
  public void shutdown();

  /** Gets the list of registered transport protocols along with the 
      property list associated with these protocols. */
  public Hashtable getSupportedTransportProtocols();
  
  /** Retrieve the TransmissionManager, which keeps track of ongoing transmissions. */
  public TransmissionManager getTransmissionManager();
}
